The SRE-FILTER for GoServe

version 1.11

Introduction

SRE-FILTER provides a number of useful features including:

This document describes how to use SRE-FILTER. While not necessary, the reader should first examine the documentation that comes with GoServe (GOSERVE.DOC and GOHTTP.DOC). Knowledge of the REXX programming language would also help. However, you can still do a lot of nice stuff with only a rudimentary understanding of GOSERV, or of REXX. Lastly, if you don't know HTML, the "markup language" of the world-wide web (WWW), then it's going to be hard to do anything interesting!

Other GoServe filters.....

A popular alternative to this filter is Don Meyer's GoHTTP HTTP filter system.
GOHTTP offers more complete CGI-BIN compatability, extensive auditing and logging, and is probably more robust under heavy loads. However, it does not seem to contain as many "ease of use" features as SRE-FILTER.

1. For convenience, let us assume that the GoServe package has been installed in the \GOSERV directory (your working directory), the data directory is set to \GOHTTP, and GoServe is running on port 80 (in HTTP mode).
2. Copy the SREFILTR.ZIP file to a temporary directory and then unzip it in the usual manner (i.e.; UNZIP SREFILTR). From an OS/2 prompt, run INSTALL (a REXX program bundled with SRE-FILTER), and follow the on-line instructions. You will be asked to provide the names of several directories.

   If you select the recommended defaults, INSTALL will create the following directories (you select which drive):

   • \GOSERV\DATA : Contains various dynamic GoServe data files: such as the message boxes, the SENDFILE, COUNTER_FILE and RECORDALL_FILE "count of hits" files, and the access control file.
   • \GOSERV\CGI_BIN : Location for CGI-BIN programs
   • \GOSERV\UPLOAD : Used to store uploaded files.
   • \GOHTTP\SAMPLES : Location of sample files, and SRE-FILTER documentation.
   • \GOHTTP\TEMP : Work area, used for temporary file creation.
   • \GOPHTTP\IMGS : Location of GIF files used by SRE-FILTER
   
   After running INSTALL, you can delete the contents of this temporary directory!

3. Using the Options item on the GoServe options page, set:
   • The filter to be SREFILTR.80
   • If you intend to run "server-side" programs, you might want to increase the following Limits:
     End client after inactive
     End client after total
   • Double check that the DataDir option points to the directory containing your HTML files (for example, /GOHTTP).
     It is HIGHLY recommended that the Data Directory and the Working Directory be different!
   • You might want to turn on GoServe's caching; if you want to record requests, you should also select the call filter anyways option.
   • To view a running log of SRE-FILTER's actions, run the PMPRINTF program.
4. At this point, the default version of SRE-FILTER is running! You'll probably want to change the values of a number of SRE-FILTER's parameters. Although you can do this by editing the INITFILT.80 with a text editor, for the new user it is probably easier to run FILTINST.HTM -- a HTML front-end to SRE-FILTER's built in configurator.

   To do this:

   • Make sure that GoServe is running on your server, with SREFILTR.80 as it's filter.
   • From your server machine, run your favorite web browser (say, Web Explorer v 1.03).
   • Open FILTINST.HTM as a URL. FILTINST.HTM is located in your data directory, hence it should be called by entering a URL of the form: http://www.your.org/filtinst.htm .
   • Select change parameters from the menu box, and submit the form
   • You will be shown an annotated FORM that lets you change most of SRE-FILTER's parameters.
   • For more advanced configuration options, you can edit INITFILT.80 See INITFILT.DOC for details on the parameters contained in INITFILT.80
   
   
5. If you need to use a port other then 80, you should:
   • Change the names of all SRE-FILTER files that end with .80 to be the .nnn, where nnn is the desired port (nnn can be > 3 digits if HPFS is being used). In particular, change SREFILTR.80 and INITFILT.80
   • Enter PORT nnn FILTER SREFILTR in the optional parameters setting of GoServe.
   • Note that it is possible to run multiple instances of the GoServe and SRE-FILTER; using different ports, different working directories (and possibly different data directories), and different copies of the user-configurable files (the .IN, .CTL, .CNT, and INITFILT.nnn files).
   • If you do run multiple instances of GoServe (with SRE-FILTER), and you use different versions of the user-configurable files, you must set the MACROSPACE_INPUT variable equal to 0. This will suppress the use of macrospace as a repository for these files. Although this will slow things down, it prevents SRE-FILTER from using the "wrong" versions of these files (that is, using the nn1 versions when a request for port nn0 is recieved).
   • Remember, when using a port other then 80, clients will need to include :nnn in the IP address of your server.

Description of the files that comprise SRE-FILTER

On changing file and directory names

If you change the names of your directories, keep the following in mind:

• If you intend to make temporary files available to clients, the TEMP directory should be a subdirectory of your data directory.
• The IMGS and SAMPLES directories should be under the data directory or in one of the virtual directories (if not, the files they contain will not be available to clients).

SRE-FILTER and macrospace

• Knowledgable administrator method: Run FILTINST.HTM, and select the reinitialize macrospace option
  Alternatively, send a !MACRO request to your server.
• Dangerous method: Clear macrospace (you can use the MSPACE.CMD program to do this).
  Warning: Macrospace is global, if you clear it you may severely upset other programs that use macrospace for their own purposes.
• Sledge hammer method: Restart SRE-FILTER
• Hacker method: Use a text editor to make an insignificant change to INITFILT.80. SRE-FILTER treats INITFILT.80 specially, and when it sees that it has changed, it updates macrospace.
• Clever but costly method: After starting GoServe with SRE-FILTER, START the MACROEYE.CMD program (a REXX program that comes with SRE-FILTER). It will check (every minute or so) the status of the macrospace routines, and update when necessary.

Citation: SRE-FILTER uses the REXXLIB library to access macrospace. This shareware package can be obtained from HOBBES.NMSU.EDU (try looking in the OS2/DEV32/REXX directory).

Variables and Parameters

Return to table of contents

The basic idea is that when writing an HTML document, special keyphrases are inserted. When the document is requested, SRE-FILTER will detect these keyphrases, and perform the desired action.

The basic structure of a keyphrase is:

• Delim1 and Delim2 are single character (or multi-character) delimiters that mark the beginning and end of a keyphrase. By default, two sets of delimiters are available (these can be changed by modifiying the INITFILT_FILE):
  { and }
  <!-- and -->
  Cautious users should use the <!-- and --> delimiters, which are also the "comment" flags of HTML.
  
• KEYWORD can be one of 6 phrases:
  • SELECT -- used to selectively include blocks of HTML code.
  • REPLACE -- used to "replace strings"
  • INCLUDE -- used to "include files"
  • OPTION -- used to "include options sent by the client"
  • INTERPRET -- used to "include the results of a custom-designed REXX routine"
  • #cmd -- NCSA HTTPD server side includes
• argument is a string containing "arguments" that are used, in conjunction with the keyphrase, to dictate how SRE-FILTER should modify this document.
• [:=] signifies that either the = or : character can be placed between the KEYWORD and the argument. Use of either = or : is strictly optional, they have no effect on the interpretation of the keyphrase.

The SELECT keyphrase is a little different: it dictates whether the "block of HTML code" that follows the SELECT keyphrase is to be retained. Thus, it is best thought of as a "server side exclude" -- the keyphrase is always removed, but sometimes so is a a lot of other stuff!

The NSCA HTTPD server side includes are provided for completeness sake; some of them are redundant with the REPLACE, INCLUDE and INTERPRET keyphrases.

Headers and Footers

To set these, just change the values of the HEADERS. (for headers) and the FOOTERS. (for footers) stem variables.

Notes:

• Headers and Footers can contain keyphrases.
• To suppress addition of a header and/or a footer, set HEADERS.1=0 and/or FOOTERS.1=0.
• The various server-side includes are only attempted for HTML files.
• If you will NEVER have server-side includes, you can set the NO_INCLUDE variable to equal "YES". This will speed up request processing a bit.

Description of Keyphrases

The REPLACE keyword is used to insert dynamically determined information and short (static) strings into a document. SRE-FILTER recognizes the following "built-in" Varnames:

• DATE : todays date (i.e.; 27 Aug 1988)
• TIME : current time (local) (i.e.; 4:54pm)
• DATEGMT : current date (at GMT)
• TIMEGMT : current time (GMT) -- a GMT is appended
• CREATION : Short message stating (local) creation time and date of the document
• CREATION_DATE : Creation date of document
• CREATION_TIME : Creation time of document
• SERVERNAME : the name of the server (i.e.; WWW.MYORG.NET)
• SERVER : the server software (i.e. GOSERVE ver. 2.45 )
• WEBMASTER : The Webmaster's address**
• USERNAME : The client's name, i.e. johndoe.somewear.net (or his numeric ip address if a name is unavailable)
• HOME_NAME : The colloquial (not necessarily IP) name of this domain**
• URL : The current URL (includes the servername and serverport)
• BROWSER: The name of the web browser the client is using (sometimes referred to as the 'User-Agent')
• FILTER_NAME : The name of the filter (i.e.; SRE-FILTER 2/96).
• REFERER : The address of the server that refered the client to your site (often unavailable).
• INHOUSE.n : n = an integer. If the user has INHOUSE privileges (but does not have SUPERUSER privileges) then replace with the INHOUSE.n variable**
• SUPERUSER.n : n = an integer. If the user has SUPERUSER privileges then replace with the SUPERUSER.n variable**
• HITS : A string stating the number of hits for the file being requested (the number of hits is stored in the COUNTER_FILE )
• COUNTS: Same as HITS, but just the number is displayed.
• OPTION_COUNTS.n and OPTION_HITS.n : Normally, the same as above. But, if an option has been recieved, use the value of the nth option (rather then number of hits).
• READ_HEAD : Displays (using a <PRE>> format) the "request header". This can be a handy debugging tool.
• PREFILTER_RESULT : Displays "status" message returned by the PREFILTR routine. If the PRE_FILTER variable equals NO, PREFILTER_RESULT will be an empty string.

• VARIABLE.varname will extract the varname variable, where varname has been set in by the SRE-FILTER program. The ambitious user can examine SREFILTR.80 (or INITFILT.80) for variable names that might be useful. For example, VARIABLE.SERVERPORT refers to the server's port (typically 80).

Last of all, if none of the above matches argument , the REPSTRGS_FILE is searched for a match. If a match is found, the information from this entry in REPSTRGS_FILE is used.

Notes

• The **'ed variables are user-configurable "static" variables that can be modified by editing INITFILT.80, or by using FILTINST.HTM.
• Dynamically determined information consists of variables that are determined at the moment the request is recieved. For example:
  <!-- REPLACE TIME -->
  will cause the current (local) time to be placed in the document.
• Static information is the same for all clients. Inclusion of static variables can be a great convenience when writing sets of HTML documents, especially if phrases that occur in all these documents are subject to frequent change (say, a daily message).

Return to table of contents

The INCLUDE keyphrase instructs SRE-FILTER to include the contents of a file into the requested document (where argument is the file-to-be-included). For example, INCLUDE PHONE.LST would cause the contents of the file PHONE.LST (in your data directory) to be inserted into the document.

Notes

• It is recommended that INCLUDE keyphrases appear on seperate lines of a file (with no other HTML statements or text).

  The file is treated as a long string (that contains linefeeds) and replaces the keyphrase -- anything before or after the keyphrase (on the same line) will be placed just before and after the contents of the file.

• FileName is interpreted relative to the Data Directory, except when the first character is a \, or a : appears in FileName. If this occurs, FileName is assumed to be an absolute name. Note that virtual directories are not used to re-map INCLUDE file names.
• INCLUDE, in combination with the INTERPRET keyphrase, facilitates customization of your documents , based on client specific informaton!

The OPTION keyphrase instructs SRE-FILTER to insert the contents of the n'th OPTION into the document.
OPTIONs are contained in the portion of the request string following the ? character.

How to pass OPTIONs to a document

• In this example ....
  OPTION 1 keyphrases in HTMLFILE.HTM would be replaced with the string Your OPTION 1
  OPTION 2 keyphrases in HTMLFILE.HTM would be replaced with OPTION2 .
  OPTION 3 keyphrases in HTMLFILE.HTM will be removed (since only two options appear in the request string).
• URL character encoding is done on the string following the ? character.
• You can have as many OPTIONs as you like, each seperated by a &.

OPTIONs and searchable indices.

When a browser responds to document containing the <ISINDEX > element, the request string will have the same HTMLFILE.HTM?word1+word2 format. In order to properly respond to such "searchable index generated" responses, you should set up an ALIAS

Notes

• OPTIONs can be very useful as a simple means of keeping track of where the client came from. For example, you can use the OPTIONs keyphrase to include message about "where you came" from in linked documents.

  The SAMPOPT1.HTM and SAMPOPT2.HTM files bundled with SRE-FILTER demonstrates this use of OPTION.

  Another example (albeit trickier), is to use OPTION keyphrases to customize URLS, with the goal of helping the client return to one of several potential "invoking" documents.
• The OPTIONs are stored in the OPTLIST. REXX "stem" variable, with OPTLIST.0 containing the number of OPTIONs recieved. This information can be used in INTERPRET keyphrases to help customize documents.

Return to table of contents

INTERPRET provides a means of including & executing REXX statements.

There are several way of specifying a REXX-code-block:

1. INTERPRET CODE statment 1 ; statement 2 ; ... ; where each statement n is a valid REXX statements (and each statement is seperated by a semi-colon). For example:
   INTERPRET CODE tmp1=server() ; interpret.result=tmp1
2. INTERPRET LABEL , where LABEL refers to a "labeled" REXX-code-block in the INTERPRET_FILE.
3. INTERPRET FILE Filename , where Filename is a file containing a REXX-code-block (filename is assumed to be relative to the working directory or to a virtual directory).

Example

If your document contains the keyphrase:

<!-- INTERPRET GO_TO_BED -->

and your INTERPRET_FILE contains a labeled code block of:

{GO_TO_BED}
tmp1=time('h') ; if tmp1<6 | tmp1>23 then interpret.results=" <em> It is late, GO TO BED! </em> " ;

{GOOD_MORNING} ....

In general, the INTERPRET code block should include one or more of the following:

1. A SAY command (use pmprintf to display SAY output)
2. A AUDIT command (stored in GoServe's permanent audit file)
3. Assignment of a (possibly multi-line) string to the INTERPRET.RESULTS variable. The contents of INTERPRET.RESULTS is written into the document (at the location the keyphrase occupies).

Notes:

• When processing a REXX code-block, syntax checking is turned on -- coding errors will cause the code-block to fail, but will not crash GoServe.
• For INTERPRET CODE and INTERPRET LABEL: each statement in a REXX-code block must end with a semi-colon.
• If your needs are complicated, you should probably generate your HTML document using an external REXX routine, and invoke it by using a server side processing request.
  However, when combined with the other keyphrases, the INTEPRET keyphrase can accomplish quite a bit of customization!
• To avoid unforseen consequences, it is recommended that temporary variables used within code blocks all have names beginning with TMP (or TMP.) In some cases (such as when using sysfiletree) you might want to DROP some of these TMP variables prior to using them.
• When using code blocks in the INTERPRET_FILE:
  each code block (such as tmp1=time('h') .. go to bed ) ends at the next {xxx} label, or at the end of the INTERPRET_FILE.
• GoServe makes available several functions and variables that may be of interest (such as the REQFIELD function).
• There are several useful SRE-FILTER procedures, including string manipulation routines, that are accessible by these REXX-code blocks (see SREFPRC1.DOC for further discussion).
• An example of combining the INCLUDE and INTERPRET keyphrases is the USE_TABLE codeblock in the default INTERPRET_FILE.
• DIRINFO.RXX and USETABL2.RXX are samples of "Rexx-code block" files.
• We recommend including short, frequently used "Rexx-code blocks" in the INTERPRET_FILE; including short, infrequently used code-blocks with the INTERPRET CODE syntax; and for longer, and infrequently used code-blocks, use of the FILE abc.rxx method is preferable.

Return to table of contents

The SELECT keyphrase

A SELECT keyphrase expects an argument containing a block of REXX code, just like the code blocks used in the INTERPRET keyphrase. This block of code will be interpreted, and the SELECT.RESULT will then be examined. If SELECT.RESULT=1 (or if it is not set), the subsequent HTML code block will be retained. If SELECT.RESULT=0, the subsequent HTML code block will be deleted. The "subsequent code block" is delimited by a SELECT END keyphrase, and can be of any length (if no SELECT END keyphrase is encountered, the remainder of the file is dropped).

Example:

       <!--SELECT  tmp.1=who ;
       if wordpos(tmp.1,owners)=0 then select.result=0; -->
       <em> Hello!  You have SuperUser Privileges !! </em>
       <!-- SELECT END -->

Notes

• When entering the beginning and end SELECT keyphrases, you must use the same set of delimiters.
• To speed up processing, it is recommended that the <!-- and --> delimiters be used with the SELECT keyphrase (rather then the { and } delimiters).
• SELECT blocks can not be nested. They may contain other keyphrases.

Return to table of contents

Support for NCSA HTTPD server side include

Details on NCSA HTTPD server side includes

• INCLUDE: Include a file.
  option can be VIRTUAL or FILE (it is ignored). The value, if proceeded by a x:\ (x is a driver letter) or a \ is assumed to be an absolute location; otherwise, the file is assumed to be relative to the data directory.
• CONFIG: Configure some options.
  option can be:
  • ERRMSG: Error message to display when a bad request is made
  • SIZEFMT : If value=ABBREV, will display kilobytes of megabytes (as appropriate). Otherwise, displays exact byte count.
  • TIMEFMT: If value=ALL, show date and time (otherwise, just the date). This is not the NCSA HTTPD standard.
• FLASTMOD: Modification date of a file.
  The option and value are the same as for #INCLUDE
• FSIZE: Size of a file
  The option and value are the same as for #INCLUDE
• EXEC: Execute a program
  option should equal CMD, and value should be a file name (relative to the working directory) of a "REXX" program. Basically, EXEC is treated the same as an INTERPRET FILE AFILE.RXX keyphrase. Note that this is not the NCSA HTTPD standard.
• ECHO: Value of a variable
  option should be VAR, value should be a variable name. This is equivalent to the REPLACE keyphrase, but with different variable names (although many of them overlap).

  The supported variables are:

  DOCUMENT_NAME, DOCUMENT_URI, DATE_LOCAL, DATE_GMT, LAST_MODIFIED, SERVER_SOFTWARE, SERVER_NAME, GATEWAY_INTERFACE, SERVER_PROTOCOL, SERVER_PORT, REQUEST_METHOD, SCRIPT_NAME, QUERY_STRING, REMOTE_HOST, REMOTE_ADDR, AUTH_TYPE, AUTH_NAME, HTTP_ACCEPT, HTTP_REFERER, HTTP_USER-AGENT

  Unsupported variables are:

  PATH_INFO, PATH_TRANSLATED, REMOTE_IDENT, CONTENT_TYPE, CONTENT_LENGTH

Return to table of contents

1. The requested document is read into memory.
2. Headers and Footers, if specified, are included.
3. Using the first "set of delimiters" (by default, <!-- and -->) the document (that now includes headers and footers) is scanned for keyphrases.
4. When a keyphrase is encountered, the appropriate server side include is performed; or if a SELECT keyphrase is encountered, a server side "exclude" may be conducted.
5. After each keyphrase is processed, step 4 is repeated (from the beginning of the file) .
6. This process continues until there are no more keyphrases (using the first set of delimiters) to interpret.
7. Step 3 is repeated, using the second set of delimiters (the { and }).

This recursive feature allows for some powerful document manipulation strictly through the use of keyphrases. In particular, the INTERPRET keyphrase can examine variables such as the "referer", the "client name", or the "OPTION list", and generate inclusions that incorporate other keyphrases (which will be processed on the next cycle of keyphrase interpretation).

For example, the SRE-FILTER is bundled with the USE_TABLE code block. USE_TABLE will ascertain the name of the Web Browser being used by the client. If the browser is recognized as understanding the TABLE element, an INCLUDE keyphrase will be generated that points to a file that uses TABLE; otherwise, an INCLUDE keyphrase that points to a file that uses an alternative to TABLE will be generated (of course, you must write both these files).
For details on this, and similar, customization shortcuts, see the the default INTERPRET_FILE

There is one caveat: Be careful you don't get stuck in a self referential loop ... you'll hang the server!

The default can be set using the DEFAULT variable.

A reminder about SRE-FILTER variables

As mentioned at the top of this document, the SRE-FILTER's parameters are set by modifying variables stored in INITFILT.80.

Return to table of contents

AUTO_NAME should contain a space delimited list of filenames to use when a request for a "directory" is recieved. SRE-FILTER will attempt to find these files in this "requested" directory -- starting with the first name in the list. To assist in this search, a special name, consisting of *.HTM (or *.HTML) means use the directory_name.htm file. Lastly, an entry of !CREATE instructs SRE-FILTER to generate a list of links to all the files in the directory (!CREATE* is simiilar, with links to subdirectories also displayed).

Example

Notes

• AUTO_NAME has no effect on calls that do not specify a directory name --that is, the document specified in the DEFAULT variable is used in response to an empty (or /) request string.
• You can point to files in subdirectories (relative to the request string) 7by entering xxx/file.htm (where xxx is the subdirectory, and xxx.htm is the page).
• If you start an entry with a /, the file is assumed to be relative to the data directory or to a virtual directory.
  Otherwise, the file is assumed to be relative to the current URL (you can include additional path information).
• If you are using .HTML as the default extension for HTML documents, use *.HTML (instead of *.HTM)
  For example: auto_name=" *.HTML INDEX.HTML PUBLIC_HTML/INDEX.HTML " (note that PUBLIC_HTML/INDEX.HTM will look in the PUBLIC_HTML directory relative to the current URL).
• !CREATE (or !CREATE*) should always be the last item in AUTO_NAME (anything following it will never be reached).
• Request strings that do not end in a /, but have no ? and have no "." extension, can be interpreted in several manners. The NOEXT_TYPE variable is used to select how these request strings are interpreted:
  • DIR : Interpreted as a directory; / is added and AUTO_NAME is used. For example, CHARITIES/HEALTH is interpreted as a sloppy form of CHARITIES/HEALTH/ (the "CHARITIES/HEALTH subdirectory of the data directory, or a virtual directory).
  • HTM or HTML : Interpreted as an abbreviation for an HTML file (with extensions of .HTM or .HTML respectively).
  • NONE: Interpreted as is.
  • other_string: The other_string is added. For example, if NOEXT_TYPE=.GIF, then .GIF will be added to these "no extension" request strings.

To select the home directory , change the value of the HOME_DIR variable.

Example

Notes

• This HOME_DIR "string replacement" does not do any syntax checking. Thus, one must be careful that the definition of HOME_DIR, and it's use in the URLs included in your HTML documents, is consistent.
• For example, if the request string in the above example had been /~/JOES/PAGE.HTM
  then the SRE-FILTER would have tried (and failed) to find /BRANCH/STAFF/PERSONAL//JOES/PAGE.HTM, (note the syntatically incorrect // ).

Each line of the VIRTUAL_FILE contains two elements: a URL starting portion and a target directory.
The starting portion is compared to the beginning of the request string. If it matches, the target directory, along with the portion of the request string that follows this starting portion, is used.

Hence, the "default data directory" (or the working directory if a server side action is requested) is not used for this URL.

Notes

• In the example, if the LOCAL/DISK1/PROJECTS virutal directory was not defined, SRE-FILTER would look for data_dir/LOCAL/DISK1/PROJECTS/BOB/PLANE.HTM (where data_dir is the GoServe data directory).
• The * after the directory name means "allow access to subdirectories". If the * had been missing, BOB/PLANE.HTM would have generated a "no access allowed" error (since only files in D:\WORK\PROJECTS are accessible).
• Example of "no subdirectory allowed access"
  STATES D:\USA\MAINE
  (a URL of STATES/AG.HTM would yield D:\USA\MAINE\AG.HTM)
• Leading and trailing slashes in the starting portion are ignored, and / and \ are treated equivalently. Similarly, trailing slashes in the target directory are ignored.

Major uses for ALIASES

1. To modify simple Action's. For example:
   You may want to substitute all requests for an Action of GETINFO with a request for:
   INFODIR/GETINFO.HTM.
   You may want to disable the !VIEWMESS facility with an ALIAS of:
   !VIEWMESS* NOVIEW.HTM
2. Processing searchable indices.
   The DOSEARCH facility of SRE-FILTER, when combined with an ALIAS, provides a simple means of implementing text-based searchable indices.

   To use SRE-FILTER's searchable index processor, one should create an alias of the form:
   INDXFILE.HTM?* DOSEARCH?FILE=FILE.NAM&TARGET=*
   Where

   • INDXFILE.HTM is the name of a searchable index (that is, an HTML document containing an <ISINDEX> element).
   • DOSEARCH instructs SRE-FILTER to "execute the DOSEARCH procedure."
   • FILE.NAM is the name (relative to the data directory, or in a virtual directory) of the ASCII text file to be searched.
   Note that the alias will not be activated on the first request for INDXFILE.HTM -- only upon return (when a ? is appended to the URL by the browser) will this alias match occur.

   If you want to use some other text search routine, you should set up an alias of the form:
   SEARCHIT.HTM?* SRCHREXX?*

   SEARCHIT.HTM is invoked at first (since the request string has no ?).
   The SRCHREXX procedure is called after the client enters the search string (and the client appends a ? to SEARCHIT.HTM). SRCHREXX should be a REXX procedure located in the SRCHREXX.80 file on your working directory.
3. Redirecting requests for moved documents
   There are 3 ways of using an alias to indicate that a document has been moved to a new server:

   target http://new.site.org/newname

   If the request string matches target, "temporary" (HTTP status code 302) redirection to the URL. A full URL must be specified (starting with http://).

   target !TEMP http://new.site.org/newname

   Same as above, but you can use short-hand's URLS (i.e.; without the http://). If you do not include an ip address, redirection will be back to the server.

   target !MOVED new.site.org/newname

   Same as above, but the redirection is permanent (HTTP status code 301).

   
   Examples:
   PROJ/P48.HTM http://www.prez.edu/truman.htm
   
   PROJ/LINCOLN/* !MOVED civ.war.org/p1/alinc.htm
   Notes:If you do not use !TEMP or !MOVED, you must specify a full URL-- do not forget the http://.
   
4. Redirecting requests for CGI-BIN programs.
   If you want to run a CGI-BIN program that is not in your CGI_BIN_DIR directory, you can use the ALIAS file to provide path information. In this case, the alias should consist of the CGI-BIN program name (without any slashes or other path information), followed by the drive and directory where it can be found.
   For example:
   If ..

   • A URL of CGI-BIN/MAKEMAP/?NEB+IOWA is recieved
   • The ALIAS file contains a MAKEMAP D:\EXES\GIS entry
   • MAKEMAP.EXE is a CGI-BIN program located in D:\EXES\GIS
   then...

   • D:\EXES\GIS\MAKEMAP.EXE will be invoked, with NEB+IOWA placed into standard input (along with all the other CGI-BIN variables stored in the environment).
   
   

   Note that if this MAKEMAP D:\EXES\GIS entry did not exist, SRE-FILTER would look for a MAKEMAP program (such as MAKEMAP.CMD) in your CGI_BIN_DIR directory.

Notes

• You can use wildcard matches and wildcard matches with substitution in your aliases (note the LINCOLN example above). This is useful if you want to redirect all request for files that used to be in a subdirectory to some new URL.
• ALIASES are processed before the AUTO-NAME replacement is attempted. Keep this in mind when considering how to handle requests that arrive with no extension, no ?, and that do not end with a /.

Return to table of contents

The NOT_FOUND_URL variable contains this customized message. By default, it's value is:
<a href="/"> Visit the '|HOME_NAME||' home page? </a> '
Thus, the befuddled client merely needs to click on this link to get some kind of access.

Note the use of the HOME_NAME variable! HOME_NAME should contain a short description of your domain; say BIG/SERVICE: Your Friendly Government Agency!.

Of course, you can set HOME_NAME=" " to send a generic message!

Return to table of contents

More specifically, when a MAPIMAGE/ substring is encountered in the action portion of the request string, SRE-FILTER will remove MAPIMAGE/, and assume the remaining portion of the action refers to a MAP file.

For example, if the request string is:

OURGROUP/MAPIMAGE/PROJECTS/BRANCH1.MAP?55,123

Type of regions recognized.

1. Circles
2. Rectangles
3. Polygons
4. Points
5. and you should always specify a DEFAULT url

However, if the distance to this closest Point is greater then the value of the MAX_POINTDIST variable, or if there are no Points specified in the MAP file, the default URL is used.

Notes:

• The MAPIMAGE/ "substring" can be modified by changing the value of the ISMAP_URL variable.
• The MAP file must be in your data directory , or a virtual directory . (i.e.; if your data directory is E:\GOHTTP, then the above example refers to E:\GOHTTP\PROJECTS\BRANCH1.MAP)
• There are several handy "map" making tools available, such as MAPEDIT.
• The SAMPMAP.HTM file that comes with SRE-FILTER (which uses SAMPMAP.MAP and SAMPMAP.GIF) provides a simple example.
• Your MAP file should, but need not, contain fullly specified URLS. The http:// will be added if missing; and if there is no IP address, your server's address (and port) are added.

Please remember that the MAPIMAGE/ "indicator string" does not refer to the MAPIMAGE/ directory!

Return to table of contents

The following steps outline how to do this:

1. Create an HTML document that returns an action that invokes a Server Side Processing request. For example, you might include a FORM element with an ACTION attribute of "/FAST1".
2. Create a file (that contains your REXX procedure), with the name xxx.80, where xxx is the action name. Note that the xxx.80 file is relative to the working directory (or a virtual directory).
   For example, if the action name is /PROGS/FAST2, and /GOSERV is your working directory, SRE-FILTER will look for /GOSERV/PROGS/FAST2.80.
3. This REXX procedure should process the Server Side Processing request, and it may call other programs (not necessarily REXX programs).
4. xxx.80 should return results to GoServe either by using the VAR or STRING completion code, or by writing to the TEMPFILE.

ddir

The data directory (typically, x:/GOHTTP/)

TEMPFILE

A temporary, "transaction specific" file (i.e.; /$341.80)

Action

The Action portion of the request string
Example (assuming the GET HTTP method was used by the client)

If the request string is: /sports/getscore?city=boston&date=July+5+1994

then the Action is sports/getscore

list

• If verb=GET: the partially cleaned up portion of the request string from after the ? ( + signs, tabs and linefeeds are converted to spaces; but URL decoding is NOT done).
  In the above example, list would be city=boston&date=July 5 1995
• If verb=POST: the body of the request

verb

Either GET, POST, or HEAD

Request string

The original request string (without cleanup or encoding).

user

The numeric IP address of the client

servdir

The "base directory", where GoServe and SRE-FILTER are located; typically, \GOSERV (set in the SERVDIR variable).

workdir

The fully-pathed name of a "temporary, working" directory that the external procedure may wish to use; by default it will be \GOHTTP\TEMP (set in the WORKDIR variable).

privset

The list of privileges granted to this client.

Infiles_stuff

A comma seperated containing: macrospace_input, list of input files: macrospace_input, access_file, user_file, virtual_file, alias_file, sendfile_file

Notes

• How does SRE-FILTER recognize a Server Side Processing Request?
  • If VERB=GET
    ... SRE-FILTER looks looks for a ? character in the request string, and also checks that the action does not have an extension of .HTM or .HTML.
  • If VERB= POST
    ... SRE-FILTER assumes it is a Server Side Processing Request.
• STATUS.80, and STATUS.HTM, contain an example of how to request Server Side Processing using a REXX procedure.
• If a syntax error occurs, SRE-FILTER will trap it and return a (probably uninformative) error message to the client.
• To call external, non-REXX programs, use the address cmd REXX command.
• If you write HTML code to TEMPFILE (for return to the client), you should return from your external REXX procedure using:
  return 'FILE ERASE TYPE text/html NAME ' TEMPFILE
• If you use a VAR or STRING "completion codes", return with nothing; that is, use:
  RETURN
• When using "local" URL's to invoke Server Side Processing Requests, include a leading / character (this avoids incorrect path assignment by the browser).
• If the NO_PROCESSING variable equals YES, NO server side processing will be permitted.

Return to table of contents

• Make sure that the CGI_BIN_DIR points to an existing directory (i.e.; /GOSERV/CGI_BIN).
• Copy the CGI-BIN program (such as a REXX file, a binary .EXE file, etc.) to the CGI_BIN_DIR directory.
• Invoke it using a standard CGI-BIN URL. For example:
  href=http://foo.bar.net/cgi-bin/test-cgi/morepath/?a+message.
• Request for CGI-BIN imagemaps (such as /CGI-BIN/IMAGEMAP/MAPFILE ) are converted into SRE-FILTER IMAGEMAP calls.
  In this example,the CGI-BIN/ is removed, yielding a call to IMAGEMAP that points to MAPFILE. (in the data directory, or a virtual directory).
• SRE-FILTER comes with a few sample CGI-BIN programs (written in REXX). The TEST-CGI.CMD file (which is copied to your CGI_BIN_DIR) will display the values of the CGI-BIN variables (invoke it using /CGI-BIN/TEST-CGI?).

Return to table of contents

Logon and access controls

PUBLIC_FILES

The PUBLIC_FILES. stem variable should list URL's that are "open to the public" -- that can be accessed by clients who have no logon rights and no access privileges.

Basically, SRE-FILTER compares the request string (using wildcard matching with substitution) against the entries in the PUBLIC_FILES. stem variable. If a match occurs:

• an alias match is done
• the clients privileges are set to PUBLICFILES PUBLIC
• the resulting request string is processed

Caution: If a client has logon privileges, and she submits a request that matches a PUBLIC_FILES entry, it will be treated as if the request came from a "complete stranger".

For a more detailed description of how to use PUBLIC_FILES, see INITFILT.DOC.

Logon Controls

Setting LOGON requirements with the CHECKLOG variable

NO

No logon required; unencumbered entry for all clients.

YES

Logon upon invocation of the default page (i.e.; an empty request string).

ALWAYS

Logon required for all requests.

INHOUSE

Entry allowed only to clients with INHOUSE or SUPERUSER privileges.

Allowing unencumbered access to IN-HOUSE users

Notes

• The * character can be used as a "wildcard" in the INHOUSEIPS. stem variables.
• Each INHOUSEIPS. value can include a client specific list of privileges (place it after the IP address).

Owners have SUPERUSER status

Logon for non IN-HOUSE users.

Note that the HTTP "basic access authentication scheme" is used to encode the username and password. This is a fairly low security method. Furthermore, the INHOUSE setting of CHECKLOG can be circumvented by clever "spoofers". In other words, SRE-FILTER is not designed for high-security environments!

Keeping out known pests

Note that the OWNERS and INHOUSEIPS.n stem variables are checked first. If the client's numeric IP address appears in either of these lists, UNALLOWEDIPS.n is not checked. Thus, by setting UNALLOWEDIPS.1="*.*.*.*", you can deny entry to everyone except OWNERS and IN-HOUSE users.

Detecting fake IP addresses

Notes

• The INHOUSE_NAME variable should contain the name of the colloquial (not necessarily IP name) of the IN-HOUSE domain. The INHOUSE_NAME variable is used in several server-generated messages.
• Once asked for an authorization, most browsers will include an "authorization field" in subsequent requests to the same site. Thus, even if CHECKLOG=ALWAYS, the client will only need to enter his username and password once (that is, she won't need to reenter it each time a different document is requested).

• When asking to view message boxes
• When performing server resets
• When invoking GETAFILE, and NO_GETAFILE_CONTROL equals either NO or INHOUSE
• When transferring files when ALLOW_ACCESS equals either NO or INHOUSE
• When processing REPLACE INHOUSE.n and REPLACE SUPERUSER.n keyphrases.

For everyone else:

Recording ALL requests for files

RECORD_OPTION can take the following values:

NO

Do not record "all" requests.

YES

Record all requests, but strip out the argument list first (for example; remove ?hi+there in ANIMALS/MONKEY.HTM?hi+there)

YES_ALL

Record all requests, do not remove an argument list.
Caution: Use of YES_ALL can lead to a very large RECORD_ALL_FILE

Record refers to updating a count of the number of times a "request string" has been recieved.
It does not mean keeping a record of each hit! If you need such detailed accounting, you can modify the AUDIT settings of GoServe (GoServe writes request information to the GOAUDIT.80 file), or you can add a custom-written routine using the post-filter option.

Notes

• Wildcard matching of entries is supported
• By default, results are written to \GOSERV\DATA \RECRDALL.CNT -- this can be modified by changing the RECORD_ALL_FILE variable.
• Each entry in the RECORD_ALL_FILE contains the request string (minus the argument list if RECORD_OPTION=YES), the number of "honored" requests, and the date of the most recent request.

  Note that this is a count of "honored" requests, not total requests -- requests for actions that are not honored (when ALLOW_ACCESS is binding) are not recorded.

• If an entry matching the requested action is not found in RECORD_ALL_FILE, a new entry will be created!
• ... however, if "wildcard matching" is enabled, a wildcard match is attempted. The use of "wildcard matching" is recommended if many temporary files are likely to be requested -- one should include a "wildcard" for the "temporary" directory in your RECORD_ALL_FILE
  
• The differences between the RECORD_ALL_FILE method, and placing a REPLACE HITS keyphrase in all documents, are:
  • Nothing is written to the requested file (the client is not given info on # of hits)
  • The RECORD_ALL_FILE is updated, not the COUNTER_FILE.
  • All requests are tracked: including transfer of HTML documents and.GIF files, and Server Side Processing requests.

  Thus, if a REPLACE HITS keyphrase is included in a document, and RECORD_OPTION is enabled , a "count of requests" will be updated in the COUNTER_FILE and in the RECORD_ALL_FILE.

Using ALLOW_ACCESS to control access.

ALLOW_ACCESS can take the following values:

YES

No limits -- all clients (with logon rights) have unencumbered access.

INHOUSE

IN-HOUSE users (and SUPERUSERS) have unencumbered access, all others must have appropriate privileges.

NO

No one (except SUPERUSERS) is given unencumbered access, all others must have appropriate privileges.

Suppressing server side includes and server side processing on a URL specific basis

Obviously, if access is not granted for a URL, the SSI_ALLOW and SSP_ALLOW variables are irrelevant!

Notes

• The default ACCESS_FILE is \GOSERV\DATA\ALL_FILE.CTL.
• Request strings that appear in the PUBLIC_FILES. stem variable are not subject to this access control (that is, the ACCESS_FILE is not checked for the PUBLIC_FILES).
• If the ACCESS_FILE does not exist, then access is disallowed to "encumbered" users. The idea is that if a request string is NOT specifically mentioned, then it should not be supported. (... and if the ACCESS_FILE is unavailable, then it can't be mentioned).
• Wildcard matching is supported.
• If the ACCESS_FILE contains a match for a given URL, but this match contains no explicit SSI_ALLOW (or SSP_ALLOW) information, server side includes (or processing) will be permitted.
  Note that global values of NO_INCLUDE and NO_PROCESSING take precedence over these privileges!
• You might want to put, as the last entry in your ALL_FILE.CTL file, some global wildcard matches . For example:
  • * NO -- if not explicitily mentioned, do NOT allow access
  • * * -- if not explicitily mentioned, allow access

NO_GETAFILE_CONTROL can take the following values:

YES

No limits -- all clients can use GETAFILE (the default).

INHOUSE

Only clients with INHOUSE privileges can use GETAFILE.

NO

No one (except SUPERUSERS) can use GETAFILE.

Return to table of contents

!ping

'PINGS' the client.

!statistics

View current GoServe statistics.

!macro

Re-load, into macrospace, the SRE-FILTER user-configurable parameter files.

Get information on IP address xxx.xxx.xxx.xxx

!reset

Resets various GoServe statistics. This is only available to SUPERUSERS, or to users with a CONTROL privilege .

!save

Saves various GoServe statistics to audit file. This is only available to SUPERUSERS, or to users with a CONTROL privilege.

!variable?var1&var2..

Returns the value of variable var1, etc. (client must have SUPERUSER privileges).

Return to table of contents

Creating a user written pre-filter

To do this, set the PRE_FILTER variable:

• PRE_FILTER=NO: no pre-filtering will be attempted.
• PRE_FILTER=YES: a PREFILTR REXX procedure will be called (with default name of PREFILTR.80 file in your working directory). PREFILTR will be called after logon privileges have been determined; when individuals do not have logon privileges, PREFILTR will not be called.
• PRE_FILTER=FIRST: same as PRE_FILTER=YES, except PREFILTR is called as the very first action (before logon privileges are ascertained).

Return to table of contents

Using a pre-filter to invoke the GoRemote package

To do this, you'll need to:

1. Obtain the GOREMOTE package, and unarchive it to either the root of your data directory, or to the GOREMOTE/ subdirectory of your data directory. You'll need GOS32.GIF, GORM*.HTM and GOREMOTE.* files. Since there are about a dozen GORM* files, placing them a subdirectory is asthetically preferable.
2. Copy GOREMOTE.80 to your working directory. If GOREMOTE was installed in a GOREMOTE/ directory, copy GOREMOTE.HTM, GOS32.GIF and GORMOK.HTM to the root of your data directory
3. Make sure that PREFILTR.80 (the one that comes with SRE-FILTER) is also in your working directory.
4. Using FILTINST.HTM (or by direct modification of the INITFILT.80 file), set the PRE_FILTER variable to:
   • YES = If you want to limit access to GoRemote:
     Clients with SUPERUSER or INHOUSE privileges will be able to view filter settings and statistics.
     Clients with SUPERUSER privileges will be able to change settings.
   • FIRST = If you want all clients to have access to GoRemote
5. Set up a link to GOREMOTE (or GOREMOTE/GOREMOTE).
6. You do not need to make any other modifications, either to SRE-FILTER, or to the GoRemote files!

Note: when calling GOREMOTE, do not call it as GOREMOTE.HTM (the GoRemote filter is not expecting to see an extension).

Return to table of contents

Post-Filter

To accomodate such needs, SRE-FILTER can be told to call a "post-filter". As with the "pre-filter", the post-filter should be a custom designed REXX procedure (with default name of POSTFILT.80.).

To do this, set the POST_FILTER variable:

• POST_FILTER=NO: A post-filter will not be called.
• POST_FILTER=YES: a POSTFILT REXX procedure will be called (which should be located in a POSTFILT.80 file in your working directory). POSTFILT will be called after a response has been sent to the client.

  Therefore, POSTFILT can not be used to modify the response sent to the client!

• amessage : a short SRE-FILTER status message
• source : The server address and client address
• request: The verb and request string
• sel: The request string
• tempfile: The temporary file used by this transaction
• params: Extra parameters (currently, the SMTP_GATEWAY variable)

Using SREF_MAILIT to issue "event specific" alerts

Notes:

• To use this facility, you must set the SMTP_GATEWAY variable to be the address of your SMTP server. If you do not have access to an SMTP server, you might be able to use OS/2's SENDMAIL program to set up your server machine as a SMTP server (see the OS/2 TCP/IP Command Reference for more information on SENDMAIL).
• Ambitious programmers can use SREF_MAILIT for more advanced e-mail purposes.

Return to table of contents

Uploading files

1. GET_URL: Upload files from another HTTP server
   • Requires that the client has ready access to an HTTP server.
   • Given this access, uploading is quick and easy.
2. PUT_FILE: Upload files from the client's own machine
   • Requires that the client be using a browser that supports the type=file FORM attribute.
   • NetScape 2.01 properly supports it (NetScape 2.0 has partial support).

1. GET_URL.

   Set up a URL with the GET_URL action, followed by the URL of the file you want to get, and the "local name". The request string should look like: GET_URL?url=http://a_url&file=file_name
   

   For example:

   • GET_URL?url=http://www.pc.com/price.lst&file=pcprice.1
   will copy price.lst (on the server at www.pc.com ) to a file named PCPRICE.1 (in the upload directory).
2. PUT_FILE.

   Create an HTML FORM with a type=file attribute. For example:

   <FORM enctype="multipart/form-data" ACTION="/put_file" METHOD="post">
     Send this file <INPUT TYPE="file"  name="userfile">
     <INPUT TYPE="submit" VALUE="send file">
   </FORM>
   

Notes

• Files must be less then UPLOAD_MAXSIZE in kbytes size; and there must be UPLOAD_MINFREE kbytes free (in the UPLOAD_DIRECTORY) after the file is uploaded. If either condition can not be met, the file will not be uploaded.
• All filenames are relative to the UPLOAD_DIRECTORY. If the filename exists, an error message will be returned.
• If you do not specify a local file name, SRE-FILTER will create a "unique" file name in your UPLOAD_DIRECTORY.
  You can specify "partially random" filenames by including ? characters in the filename. SRE-FILTER will attempt to create a unique file name by appropriate substitutions of the ? character. For example:
  • if filename=ABC??.TXT,
  • and ABC01.TXT exists,
  • then SRE-FILTER will use ABC02.TXT.
• For GET_URL: You must completely specify the URL (including the http:// portion).
• A short status report on success of the upload operation is written to the UPLOAD_LOG file.
• For PUT_FILE: Browsers that do not support the type=file FORM attribute will send back garbage (that will be ignored).
• UPLOAD.HTM contains an example of the use of GET_URL and PUT_FILE.

Return to table of contents

Automatic generation of response headers

To do this, set the value of the AUTO_HEADER variable:

• NO : Do not create response headers
• HEAD: Create response headers when a HEAD HTTP method request is recieved for an HTML document.
• ALWAYS: Create response headers whenever a GET or HEAD request is recieved for an HTML document.

Notes

• GoServe automatically generates several response headers (such as content-length and file-creation-date).
• Server side includes (that might be in the <HEAD>) are not processed when a HEAD request is recieved, but are processed when a GET request is recieved.

Return to table of contents

Using DOSEARCH.HTM

DOSEARCH details

By default, a paragraph is defined as being all text between blank lines. Alternatively, one can define paragraphs as single lines, or as delimited by any arbitrary character sequence.

A search string is comprised of "targets" There are two kinds of targets: subwords and phrases.
Each space delimited entry in the search string is treated as a seperate subword, except..
for phrases, which are delimited by parenthesis; for exampe:( xx yy zz )
.... and phrases must be matched precisely.

Search algorithims.

Simple mode with highlighting.

 Two meta-commands and 4 "target specific"  instructions are recognized.
        Meta-commands are signified by  *&  or *\ at the beginning
        of the search string.
             *&   means "find paragraphs that match ALL targets in
                the search string"
             *\  means "find paragraphs that match NONE of the targets in
                 the search string"
     If there are no meta-commands, the following target specific
     commands are recognized.
          &   means "paragraphs MUST have this target"
          |   means "accept paragraph if it has this target"
              Note that | is the default (assumed if no target specific
              command entered).
          \ means "paragraph must NOT have this target"
          % means "accept paragraph if it does NOT have this target"

    Summarizing: to be a "found" paragraph:
      Test 1a) Any (of several) | targets must be present,    or
           1b) All of the % targets must be missing
         If pass test 1a and 1b, then
           2a) None of the \ can be present, and
           2b) All of the & must be present
     If present, all & and | targets will be highlighted.
     Note that if there are no % targets specified, test 1b is ignored.

Logical expression mode without highlighting

A sequence of words without any operators is treated as a phrase -- to treat each word as a seperate subword, put ( ) around each one. Basically, when using this mode, be liberal in your use of ( ).

DOSEARCH Options

Technically speaking, the options appear in an option list, with each option seperated by an & character.....

• if the GET method was used, the option list is placed after a ? character in the request string.
• If the POST methed was used, the option list is placed in the body of the request.

The option list should have the structure:
option_name=option_value&option_Nam2=option_value2&...

The DOSEARCH options are:

       DELIM : The paragraph delimiter.
                   " "  or 0 = blank lines   (the default)
                   "$"      = Each line is a paragraph
                   other     = User specified delimiter
       LINE  : Maximum number of lines to display of each "found" paragraph.
                 If 0, no lines displayed (a summary will be displayed)
                 Default is to display all lines.
       NUM   : YES=Display the line or paragraph number,
               NO=Don't (default=YES)
       BAR   : YES= Seperate each paragraph/line by a horizontal bar,
               NO=Don't (default=YES)
       EXPERT: YES= Use "logical expression mode",
               NO=Use simple mode (Default=NO)
       FILE  :  FILE=filename
                A file to search (either relative to the data directory,
                or in a virtual directory).  You can include as many FILE
                options as desired (each entry will be searched in turn).
                Furthermore, * and ? wildcards can be used.
       SEARCH: The search string
       CASE  : If YES, then search is case sensitive (default is NO)

Examples

Simple mode examples

( The best car)

Finds paragraphs containing the phrase the best car

car truck motorcycle

Finds paragraphs that contain one (or more) of car, truck or motorcycle

dog cat & store (pet pig)

Finds paragraphs that contain one (or more) of dog, cat or the phrase pet pig; and that also contain store

*& computer price memory

Finds paragraphs that contain computer, price, and memory (must have all of them, but can be in any order)

Logical mode examples

The best car

Finds paragraphs containing the phrase the best car

car | truck | motorcycle

Finds paragraphs that contain one (or more) of car, truck or motorcycle

( (dog & cat) | (pet pig) ) & stores

Finds paragraphs that contain stores, and that contain either both dog and cat, or the phrase pet pig

Return to table of contents

Usage: Set up a URL that generates a request string of the form: /getafile?option1&option2&..&optionN"
Alternatively, use (or modify) GETAFILE.HTM.

GETAFILE allows any users the ability to see, and easily retrieve, all files in (or under) the data directory. If this is undesired, you can disallow the use of GETAFILE for selected classes of users..

GETAFILE options

Specifying which directory to display

DIR=dirname

The directory to view. Dirname is actually a subdirectory under the data directory, or a virtual directory. Thus, DIR=/ means "display contents of Data directory"
Note: if DIR= is missing, then DIR=/ is assumed.

ROOTDIR=rootdir

The ROOTDIR is used to limit high up the directory tree GETAFILE will go. This can be useful when you want to allow someone to look at a subdirectory of your data drive, but not the whole directory. Note that DIR should be an abbreviation (or exactly equal) to ROOTDIR.

Hint: You can set it to be the same as DIR by using ROOTDIR=!.

SHOWDIR=YES or SHOWDIR=NO

If YES, then display the subdirectories (of the select directory). The default is NO.
Subdirectories are displayed as links back to GETAFILE; this permits traversal of the directory tree using mouse clicks.
Parent (the .. directory) is also included, but NOT if DIR=/.

Specifying a header and "introductory text"

header=a+header+message

The message string will be inserted as an <H2> at the top of the document.
Example: header=(From+our+staff) (note the use of URL encoding)
If not specified, a default header is used.

DISPFILE=filename.ext+a+message

Displays the contents of a file (with the name filename.ext), that is located in the DIR= directory. The optional "a message" will be used to describe the DISPFILE (if missing, the file name is used)

LINES=nlines

Sets the maximum number of lines to display from the DISPFILE= file (default is to display the entire file). This is ignored if there is no DISPFILE= option specified.

TOP=YES or TOP=NO

Put the DISPFILE= file at the top of the document (default is to put at the bottom). TOP= is ignored if there is no DISPFILE= option specified.

Specifying what file specific information to display

SHOWDATE = YES or SHOWDATE=NO

If SHOWDATE=YES, then the file's creation date is displayed (by default, SHOWDATE=NO).

SHOWSIZE = YES or SHOWSIZE=NO

If SHOWSIZE=YES, then the file's size in bytes (or K bytes) is displayed (by default, SHOWSIZE=NO)

GIFS=YES or GIFS=NO

Put a "cute picture" next to the filename (or directory) (courtesy of the GoHTTP HTTP filter ) .

Using Tables to Display files and directories

TABLE = DIR, or TABLE=FILE, or TABLE=KEY, or TABLE=NO

Display results using a table (by default, TABLE=NO).

• NO : Do not use a TABLE (display files and directories on seperate lines)
• DIR : Put the files & subdirectories in a multi-column table
• FILES : Create a multi-column table containing:
  1. File & directory names (note that the file names do not include the directory name)
  2. File size (if SHOWSIZE=YES)
  3. File date (if SHOWDATE=YES)
  4. If TABLEFILE is selected, a line from it is displayed.
• KEY: Similar to FILE, but instead of displaying the ith line of the TABLEFILE in the ith row of the table, a key search is performed on filename. Keys are defined by identifiers that are enclosed in { } brackets. The text following a key is the key's message.
  Example: {afile.1a} a description of this file {afile.2}
  If the file name (in column 1) matches the {afile.1a} key then the string a description of this file will be displayed in column 4.

  Note on directory names: To be recognized, keys for directory names must contain just the subdirectory name (not the path information).
  For example, if you specify DIR=PUBLIC\, and PUBLIC\ contains the JAN96 directory, the key file (in the PUBLIC subdirectory of the data directory) should contain an entry of {JAN96)

If your client's browser does not support tables, you should set TABLE=NO.

TABLEFILE=filename+a+message

TABLEFILE is used when TABLE=KEY or TABLE=FILE is specified. It should contain "descriptive" information on the contents of the directory to be included into the TABLE of filenames & directories. As with the DISPFILE, the TABLEFILE should be in the DIR= directory. Also, the "a message" is displayed as a "column header".

TABLECOLSs=n

n is an integer between 2 and 5. By default, equals 4.
This is used if TABLE=DIR is selected. It specifies the number of columns in the table of files/subdirectories.

USEDL=YES or NO

If USEDL=YES, and TABLE=FILE or KEY, a <DL> list will be used instead of a table. This can be convenient when talking to browsers that do no support tables, or when there is a lot of descriptive material.

Using SENDFILE to limit access / record transfers

RECORD=YES or RECORD=NO

Use the SENDFILE facility of SRE-FILTER to transfer files to the client. The default is RECORD=NO.

The use of RECORD=YES provides some access control, but it is easily circumvented (a moderately clever user can remove the RECORD=YES option from the request string!). If security is important, you probably should disable GETAFILE , or enable the ALLOW_ACCESS variable.

ACCESS=an access code

ACCESS information (along with logon privileges) is used by SENDFILE when RECORD=YES.

FORCETEXT=YES or NO

If FORCETEXT is only relevant when RECORD=YES is chosen.
When FORCETEXT=YES, GETAFILE (actually, SENDFILE via GETAFILE) will assume that all files are of "mime-type text/plain". This is a useful way of forcing the client's browser to display all files (even files with non standard extensions, such as RESULTS.O1). This trick relieves the client of the necessity of running a "helper application" (which can become tiresome). The downside is that if GIF and other non-text files are selected, the browser will display junk. Use this option with discretion!

Miscellaneous

IMGDIR=directory

Specifies the subdirectory (of your data directory) that contains the "cute pictures" (GIF files) used by the GIFS=YES option.
Hint: Use the TYPE="hidden" attribute element in the NAME="IMGDIR" INPUT element.)
Example: imgdir="/IMGS2" instructs SRE-FILTER to look in the IMGS2 subdirectory for the "little GIF" files.
If IMGDIR is not specified, then the gifs are assumed to be in the IMGS subdirectory (of your data directory).

SENDFILE is invoked with a request string of:
SENDFILE?filename&access=access_code&forcetext=ans

SENDFILE will ...

1. Check for the existence of filename ( filename is assumed to be relative to the data directory or relative to a virtual directory).
2. Look in the SEND_FILE for an occurence of filename
3. If an entry for this filename is found, extact a list of "acceptable privileges" for this filename
4. Transfer the file if:
   filename was not found.
   If filename was found, then transfer the file if:
   The access_code appears on "acceptable privileges" list, or
   The client has a privileges that appears on this list, or
   The list is empty (that is, there is no list), or
   The list equals *,
5. If filename is transfered, the "count of requests" for this file is augmented (that is, the SEND_FILE is updated).

Notes

• By default, SEND_FILE is \GOSERV\DATA\SENDFILE.CTL.
• If the "acceptable privileges" list equals NO , SENDFILE will not transfer the file (and will not augment SEND_FILE).
• The NO_GETAFILE_CONTROL variable has no effect when SENDFILE is directly invoked.
• When ACCESS_ALLOW is binding, SENDFILE will first check the ACCESS_FILE , and if access is allowed it will then check SEND_FILE.
• SENDFILE supports wildcard matching.
• If FORCETEXT=YES, SENDFILE will assume that all files are of "mime-type text/plain". This can be a useful trick (it tricks the client into displaying everything as a text file), but if .GIF (or other non-text files) are chosen, garbage will be displayed ( use this option with discretion)!

Return to table of contents

The message box facility consists of two components:

1. A message writer. The message writer is invoked with a a request string of:
   MESSAGE?messtype=messagebox&field1=value&..&fieldn=value
2. A Message Reader. The message reader is invoked by a request string of:
   /VIEWMESS?messbox=message_box

The Message Writer

MESSTYPE (recommended)

The particular message-box to put the note into. If MESSTYPE is not included, the note will be put into the ANYONE message-box. If MESSTYPE names a non-existent message-box, a new message-box will be create.

NAME, FAX, E-MAIL, ADDRESS, PHONE, and SUBJECT (optional).

The name, and value of these fields are written to the message box.

Other names (optional).

The name, and value, of these fields will be written to the message box.

The difference between "other names" and the NAME, etc. fields is merely in the order of appearance, and the style used to write the information.

MESSAGE (recommended)..

The (multi-line) message. It's written last of all.

The Message Reader

A request string of !VIEWMESS?messbox=message_box will cause SRE-FILTER to transfer the message-box-file to the client.

Notes

• To limit message box "write" access, create an entry in the ACCESS_FILE of the form:
  MESSAGE* access_privilege_list
  (and you may also want to create similar entries for !VIEWMESS and !ASKMESSBOX)
• When using !ASKMESSBOX, if the client does not have VIEWMESS privileges, she will be queried for a username and password. This is useful when logon is not required -- one can set up a special entry in your USER_FILE, possibly shared amongst a set of individuals, that has VIEWMESS as a privilege.
• Note that if you want all IN-HOUSE users to have message box privileges, you should add VIEWMESS to the INHOUSE_PRIVS list
• The !VIEWMESS action does not check for VIEWMESS privileges (actually, !ASKMESSBOX, upon ascertaining VIEWMESS privileges, returns an on-the-fly-constructed document that contains a FORM that points to !VIEWMESS).
  In other words, these message-boxes are not very secure!

  Hint: to limit access to !VIEWMESS, create a !VIEW* priv_list entry in the ACCESS_FILE .

Return to table of contents

• SREF_MEDIATYPE: Return the MIME type of a file (based on it's extension)
• SREF_REPLACESTRG : Replace substrings
• SREF_GRAB_FILE : Wait for file to become unlocked, and then read it into a a variable.
• SREF_FIX_URL : Given a local URL, and servername, and a serverport, return a legitimate URL (including the http://).
• SREF_WILDCARD : Perform a wildcard substitution.
• SREF_JULDATE: Return the Julian date and time (days since 0/0/0, time in fraction)
• SREF_MAILIT : Send an E-mail message.

User-configurable SRE-FILTER files.

Changes to the INITFILT_FILE can be accomplished in several ways:

1. You can edit it with your favorite text editor. You might want to examine INITFILT.DOC for a detailed discussion of the meaning, and possible values, of each variable included in the INITFILT_FILE.
2. From the server's own computer, access FILTINST.HTM with your favorite web browser (it should be in the data directory). FILTINST.HTM provides a "customized for your server" FORM's based front end to SRE-FILTER's built-in configurator. With FILTINST.HTM it is easy to change most of SRE-FILTER's parameters.
   If you need to modify the few parameters that FILTINST.HTM (purposefully) ignores, you'll have to hand edit the INITFILT_FILE(and read INITFILT.DOC first!).

   Cautious server administrators may wish to remove FILTINST.HTM from the data directory to minimize risk of tampering by unauthorized (but very clever) clients. Casual server administrators can modify FILTINST.80 to permit remote configuration.

• Parameters in the INITFILT.80 file include:
  Name of the in-house" domain
  Numeric IP addresses of the "in-house" domain
  Messages to display to "in-house users" only
  Numeric IP addresses of "owners" (who are given SUPERUSER status)
  Names of various SRE-FILTER support files (such as the USER_FILE and the COUNTER_FILE).
  Name of default (home) page.
  Messages to include as "header" or "footer" for all requested HTML documents.
  Name/e-mail address of the "webmaster" (used by some server-side actions)

Return to table of contents

Return to table of contents

The counter file has syntax:
AURL CTS MESSAGE_1 , MESSAGE_2

Lastly, a "count of hits" string is included in the the requested document. This string will have the form:
Message_1 cts+1 Message_2
a generic message_1 is used if message_1 and message_2 are missing

For REPLACE COUNTS, the same procedure is followed, except message_1 and message_2 are ignored.

If the requested html document does not match any of the aurl's, a new entry will be created (with CTS=1 and message_1 and message_2 left blank).

Example

INDEX.HTM  66 You are visitor # , since {replace creation_date }
PROJECTS/PROJ1.HTM  19
CALC/CALC.HTM  9
OVERVIEW.HTM  13

Notes

• The requested URL may differ from the URL recieved by GoServe (say, due to ALIAS or ~ modifications). Also, any argument list (following a ?) is removed.
• The default name of the counter file is \GOSERV\DATA\COUNTER.CNT. You can modify this by changing the COUNTER_FILE.
• Wildcard matching is not attempted.
• An alternative means of recording "number of requests" is provided by setting the RECORD_OPTION variable.
• Another alternative is the SENDFILE facility, which keeps track of explicitily requested files.
• In the COUNTER_FILE (and in the ACCESS_FILE, the SEND_FILE, and the RECORD_ALL_FILE) ...
  / characters are converted to \ characters; and leading \ characters are dropped.
  lines beginning with a ; are comments.
  Another alternative is to use external programs to generate a "counter GIF". Many of these programs will also keep track of the number of hits. For example, XCOUNT.CMD (a CGI-BIN program) will generate a simple "odometer" style counter, and also keep track of the number of hits (note that this doesn't work if the client has her browser set to not load graphics).

Return to table of contents

The structure of the RECORD_ALL_FILE is similar to the COUNTER_FILE, with a few exceptions:

Example

PROJECT/PROJ1.HTM  9 03/01/96
TEMP/ZFVL5615.LST  1 02/28/96
DOSEARCH  4  2/29/96
OVERVIEW.HTM 7 03/01/96
TEMP/*  3 03/01/96

Also, note that the date is the date of the most recent "allowed" request.

Notes

• The RECORD_ALL_FILE is meant strictly for recording information -- it does not contain message strings, nor does it contain "access control" information.

Return to table of contents

The structure of SEND_FILE is:
FILE_NAME #_of_times_sent access_list

The access_list is optional. If present, file transfer will occur only if the client has provided an "access code", or has a privilege, that appears in this access_list.

Example

WORKAREA\PROJ1.DOC  9
WORKAREA\PROJ2.IN  7 DRH APOLLO
\USAGE.TXT  2
\DONTREAD.ME 1
PUBLIC\* 2  *

Notes

• Wildcard matching is supported.
• If there is no entry for a filename, or if an entry does not contain an access_list, the file will be transferred (assuming that ALLOW_ACCESS is not binding).
• If SENDFILE is called with a file name that does not appear in the SEND_FILE a new line will be added.
• If a SEND_FILE does not exist, it will be created.

The structure of ACCESS_FILE is:
FILE_NAME access_list , ss_options_list
The access_list and the ss_options_list are optional. Note that the ss_options_list should follow a comma, and should consist of a space delimited list of options. Currently, two options are recognized: NO_SSI and NO_SSP

If present, the request string will be honored only if one of the client's privileges appears in the access_list.
If honored, server side includes will not be done if NO_SSI occurs in the ss_options_list. Similarly, server side processing will not be done if NO_SSP appears.

Example

WORKAREA\PROJ1.DOC   INHOUSE
WORKAREA\PROJ2.IN   INHOUSE MERCURY
USAGE.TXT   NO
WEATHER*  INHOUSE
READ.ME
!VIEWMESS?messbox=SECRET2*  INHOUSE
PUBLIC\*   *
GUEST\*  *  ,  NO_SSI NO_SSP

Thus, given that ALLOW_ACCESS is binding ..

• WORKAREA\PROJ1.DOC will only be sent to clients having INHOUSE privileges
• WORKAREA\PROJ2.IN will only be sent to clients having INHOUSE or MERCURY privileges.
• USAGE.TXT is never sent
• All actions (say, a set of WEATHER prediction program) with names starting with WEATHER are available to users with INHOUSE privileges.
• READ.ME is always sent
• The SECRET2 (or SECRET2x) message box can only be examined by clients with an INHOUSE privilege.
• All files in the PUBLIC directory are always sent.
• All files in the GUEST directory are sent, but no server side includes (or server side processing) is attempted for these files.

Notes

• Assuming that ALLOW_ACCESS is binding...
  • if there is no access_list, the file is sent to the client,
  • if a file does not appear in the ACCESS_FILE, either explicitily or as a wildcard, the file will not be transfered,
  • If the ACCESS_FILE does not exist, the request string will not be honored.
  • If the access_list equals NO, the request string will not be honored.
  • If the access_list equals *, the request string will be honored.
  • If the ss_options_list is missing, server side includes and server side processing will be permitted.
  • The suppression of server side processing on a per-URL basis is tricky: since the URL invoking the server side processing is not the same as the URL that invokes the FORM containing document. Use it with care!

1. When logon is required of a client.
2. When information on privileges is needed.

The structure of the USER_FILE is:
NAME PASSWORD PRIV1 PRIV2 ...
Note that the PRIV1 is required, while other privileges (PRIV2, etc.) are optional.

Example

  DANIEL A11S34WZ SUPERUSER
  MIKE IOWAMAN  CONSULTANT
  JILL GOBOTS      INHOUSE
  JOHN  KIOWA    INHOUSE  VIEWMESS
 ANONYMOUS *  PUBLIC

• DANIEL is given SUPERUSER privileges. This could be useful if DANIEL needs to reset the server from an out-of-town site ... but it could be dangerous (so use an obscure password)!
• JILL and JOHN are IN-HOUSE users. Thus, if CHECKLOG=INHOUSE, then DANIEL, JILL, and JOHN are allowed in, but MIKE is not allowed in (MIKE is allowed in, given correct entry of his username and password, if CHECKLOG does not equal INHOUSE).
• JOHN is given VIEWMESS privileges (as well as INHOUSE privileges).
• ANONYMOUS is given PUBLIC privileges, and can use any password.

  Note that * means "anything matches", and can be used in either the password or username fields.

Return to table of contents

ALIASES file (ALIAS_FILE)

The ALIAS_FILE contains lines having the structure:

 alias_target replace_string

Note that to support non-exact matches, several special character strings may be placed in either the alias_target or replace_string:

• The * character in the alias_target signals that this alias_target can be used in "wildcard matching"
• If a * appears in both the replace_string and the alias_target, then an "wildcard match with substitution" may be performed.
• If the replace_string starts with !TRANSFER, then the (rest of) the replace_string is assumed to be an absolute file name (that is "not necessarily in the data directory"). Note that this !TRANFER syntax provides a limited alternative to virtual directories
• If the replace_string starts with http://, then the remainder of the replace_string is assumed to be the URL for a redirection response to the client. Similarly, if replace_string starts with !TEMP or with !MOVED, a "temporary" or "permanent" redirection response will occur.

Example

; This first example replaces a  "bad request string" with
;a correct HTML file names

HOME INDEX.HTM

; The next example would be used if CHECKCAT.HTM was a gateway to a
; "searchable index" (CAT.DAT being the file that is actually searched).

CHECKCAT.HTM?* DOSEARCH?FILE=CAT.DAT&SEARCH=*

; This redirects all requests that begin with YAH to yahoo
YAH* http://www.yahoo.com/

; This sends some "not in data directory" documentation to the client.
WHATGOT !TRANSFER=E:\PRODUCTS\DESCRIBE.DOC

; This performs an "wildcard match with substitution, in combination with
; a redirection).  Typically, this would be called as WEBSEARCH?find_this
; (the ? is retained in the * substitution)
WEBSEARCH?* http://www.webcrawler.com/cgi-bin/WebQuery/?*

CAUTION

we highly recommend that all "wildcard match aliases" have "targets" that do NOT MATCH pre-existing files, directories, or "actions".

Return to table of contents

Summary

Known limitations of SRE-FILTER

• SRE-FILTER has not been tested with proxy servers
• Server push can be implemented using external rexx routines, but SRE-FILTER provides no explicit facilities to assist in developing such mutli-part-with-replacement documents.
• "Byte range retrieval" is tested, but should be viewed as experimental (GoServe can be a bit flakey when processing multi-part sends).
• SRE-FILTER does not provide a high level of security. However, as long as one is careful with virtual directories, ALIASES, and INTERPRET and INCLUDE keyphrases, clients should be limited to the data directory tree (and explicitly mentioned "virtual" directories).
• Although SRE-FILTER incorporates conflict avoidance, it's performance under heavy load has not been examined.
• GoServe's caching is supported for most, but not all, file transfers. Caching is disallowed whenever logon or access control are active, whenever a byte-range is retrieved, and when there is a possibility that a server side include will occur.

  When caching is on, and a cached file is requested, GoServe may call the filter anyways (see the Options-General tab of GoServe). If this should occur, SRE-FILTER will detect that the file has already been transfered, and SRE-FILTER will appropriately record the request (if RECORD_OPTION is active).
  Note that the COUNTER_FILE file will not be augmented (COUNTER_FILE is augmented via a server side include, and files with server side includes are never cached).

• The various initialization and control files are "system wide" -- there is no facility for maintaining "auditing and control" files on a per directory basis.
• SRE-FILTER has some speed-of-transfer optimization, but the primary design criteria was flexibility.

• Logon's may be required of no one, everyone, or the general public.
  • A set of public files, and directories of files, can be specified -- these will be available to all clients, without checking logon rights.
  • OWNERS (with SUPERUSER privileges) and IN-HOUSE users can be automatically detected (using their numeric IP address), with logon requirments waived.
  • A set of "unallowed" numeric IP addresses can be specified.
  • Wildcards can be used in the list of IN-HOUSE and "unallowed" numeric IP addresses
  • Logon information (for everyone else) are easily granted by modifying a text file.
• Several tools for resolving URL's are provided
  • A "directory specific" document can be sent when a request string specifying a directory, but no file is name, is recieved
  • ALIASes can be used to redirect requests for moved documents, to resolve commonly occuring "misspelled requests", and to transfer specific files from anywhere on your server.
  • A customized "not found" document (complete with suggested link) can be sent when the requested document is missing.
  • The ~ shorthand for the "home directory" is supported.
  • Transfer of files from outside the "default data directory" is easily supported through the use of "virtual directories".
• A variety of server-side includes are easily achieved
  • Headers and Footers can be included in all documents
  • Recursively processed keyphrases, that dictate server side includes, can be placed in your documents
    • Dynamic and Static String REPLACEments
    • Inclusion of files (from anywhere on your system)
    • Inclusion of OPTIONs that appear in the request string (after a ?)
    • Execution of REXX-code blocks, and insertion of the results
    • SELECTive excludes of HTML code blocks
  • Partial implementation of the NSCA HTTPD server side include syntax
• Standard server features include:
  NCSA style IMAGEMAPS are supported, and easily requested.
  searchable indices on text files are easy to setup
  several mechanisms for keeping track of file requests
  several mechanisms for controlling access to selected files
• Special SRE-FILTER built-in features include:
  a file display and transfer facility with easy directory traversal and optional file access control
  a simple but powerful "text file" search facility
  simple message-box facility is built into SRE-FILTER.
  implementation of "byte range retrieval" (used by Adobe Acrobat Amber to access subsections of documents)
  Reponse headers can be automatially generated, using LINK and META HTTP-EQUIV elements in the <HEAD> portion of the document.
  support for the SWISH "directory indexer" program.
• Several file upload methods are supported
  Client directed retrieval of files from other HTTP servers
  Browsers that support the type=file FORM attribute (such as NetScape 2.01), can upload files from their own machines.
• User written server side processing (gateway programs) options include:
  Support for REXX routines that return results directly to the client.
  CGI-BIN programs (both REXX and binary executables) are supported (using procedures adapted from the GoHTTP package).
  a library of REXX-procedures includes simple e-mail, http retrieval, and string manipulation routines.
• A "pre-filter" can be called prior to invoking SRE-FILTER
  SRE-FILTER comes with a special pre-filter that implements the the GoRemote package.
• A "post-filter" can be called after SRE-FILTER has responded to the request.
  SRE-FILTER comes with a special post-filter that uses socket calls, to an SMTP server, to e-mail "event specific" alerts.

Return to table of contents

The \ and / characters

The / character is used in URLS to "indicate hierarchical structures, such as directories". It is equivalent to the \ OS/2 (and DOS) character. Thus, / that appear in a request string are converted into \ when SRE-FILTER needs to find a file.

Action

The action is the "location" portion of the request string.

• If the GET method was used -- it's the part after the first / (that ends the domain name) and before the first ? (or the end of the request string, if no ? is present).
  Examples:
  • In http://rpbcam.econ.ag.gov/calc/calc.htm,
    the action woud be calc/calc.htm.
  • In: http://foo.bar.net/workdir/myfile.htm?not+readyl,
    the action would be is workdir/myfile.htm.
  • In:http://young.kids.com/toys/demo?dogs+cats,
    the action would be toys/demo
• If the POST method was used, the request string (not including a leading / character) is the action (there should never be a ? in a POST method request string). All other information is contained in the "body" of the request. SRE-FILTER assumes that all POST method requests are for Server Side Processing.

Alias

SRE-FILTER uses "aliases" to perform textual substitution. Typically, an alias is used to replace a simple request string with a more complicated one. In addition, aliases are used for several special purposes: implementing "searchable indices", document redirections, and specification of the location of CGI-BIN programs.

Client

The Client (sometimes referred to as the requester) is the individual requesting file(s), or Server Side Processing, from the server. Typically, the request was generated by someone running a Web Browser, and clicking on a link or submitting a FORM.

Request string

A request string is sent to the server by a client, it contains a "request" for a server action (such as transferal of a file, or a request for Server Side Processing).
In this documentation, "request string" connotes the portion of a "selected URL" after the first / character (after the domain name). If a GET HTTP method was used, the client may append a ? chararacter, followed by additional information (for example, a pixel location if a mappable image has been selected). In a POST method request, the request string only contains the name of the "Server Side Processing" routine, all additional information is transferred in the body of the request.

Note that in this documentation the leading / is not written when sample request strings are displayed -- the request string is the portion AFTER the first / in the URL!

CGI-BIN

CGI (Common Gateway Interfact) - BIN is a standard by which server side ("gateway") programs can be invoked. It uses environment variables to pass data, as well as standard input and output. SRE-FILTER supports CGI-BIN, using procedures from the GoHTTP package. Although this support should permit use of most CGI-BIN programs, the use of the "native" SRE-FILTER interface (using REXX programs that are passed information in the argument list) is recommended.

Data Directory

The Data Directory (typically, \GOHTTP) is the directory that contains your HTML documents, images, and other files accessible to clients. Given that there is no "matching" virtual directory, all requests for files (such as HTML documents) are relative to this directory.
Thus, if

• a request for MYFILES/PROJECT1/BIGTASK.HTM is recieved
• your data directory is E:\GOHTTP

then, SRE-FILTER will look in E:\GOHTTP\MYFILES\PROJECT1 for the BIGTASK.HTM file.
A Note On Data Security

In general, the only files available for clients are those in (or under) the Data Directory. Exceptions to this rule include:

Files explicitly transferred by user-written REXX code. Note that user-written Rexx code may be invoked by a Server Side Processing Request, by an INTERPRET keyphrase, or by a SELECT keyphrase.

For HTML files, the INCLUDE keyphrase can be used to include non-data directory files.

A !TRANSFER "alias" can be used to access files from anywhere on the server.

Virtual directories can point to anywhere.

Summarizing... non-data directory files can be obtained only when the server administrator explicitily permits it (albeit, there are several means by which this permission may be granted).

ELEMENT

ELEMENT's are the constituent parts of an HTML document. They dictate the structure, layout, and display characteristics of an HTML document. ELEMENTS are identified using HTML tags, where an HTML tag consists of text within < and > characters. Often, a start and stop tag are used.

For example:

• <H1> Welcome </H1> : defines a "level 1 Header"
• <A href="/morejunk/stuff.htm"> More info? </A> : defines a link to a local document.

File Names: Absolute and Relatve

SRE-FILTER can treat File Names as "absolute" names or as "relative" names. Absolute names should be fully pathed -- containing the complete path to the file (sometimes the drive letter will be missing, in which case the GoServe drive is usually assumed). Relative names are assumed to be in subdirectories of some assumed default. For example, when a client asks for a file name, it is always assumed to be relative to the data directory (that you set in the GoServe options menu).

FORMS

The HTML FORM element is used to create a fill-in form. A FORM element typically contains an ACTION attribute, as well as a number of elements that provide editable fields (for the client to fill in or to otherwise select). Typically a form is designed in tandem with a server-side program.

Although not the only way to generate a Server Side Processing Request (one can use sets of detailed URLS), FORMS are probably the easiest for the average client to deal with.

HTTP : Hyper Text Transfer Protocol

The rules by which web-aware clients and servers communicate.

HTTP method (also known as the VERB)

SRE-FILTER recognizes three HTTP methods: GET, POST, and HEAD. GET requests contain all information (action name and optional parameter list) in the request string (with the parameter list placed after a ? character); while POST requests contain only the action name in the request string (the "body" of the request contains the parameter list). Currently, SRE-FILTER assumes that all POST requests are requests for Server Side Processing. HEAD method requests are sent "meta information" on the requested file, the file itself is not sent.

HTML

Hyper Text Markup Language (HTML) is the protocol used to create documents designed for display by WWW browsers (such as Netscape, Mosaic, and IBM Web Explorer). Basically, HTML consists of a set of formatting commands, which are included in a file containing the text to be displayed.
Note that to be recognized by SRE-FILTER as an HTML file, a file must have an .HTML or .HTM extension.

Although there is a formal HTML standard (currently 2.0, with 3.0 under discussion), it is not rigidly adhered to. In particular, NetScape has it's own extensions; many of which are not recognized by other browsers. For example, IBM's Web Explorer ver 1.03 recognizes the CENTER element, and the SIZE attribute of the HR element, but not the FRAMES element.

Imagemap

An image map (sometimes called a mappable image) is an inline image which, when clicked with the mouse, returns a pixel location to the server. Typically, the server then translates the pixel location into a URL, and redirects the client to that URL (which might be on an all together different server). SRE-FILTER supports image maps using the MAPIMAGE/ "indicator string", along with NCSA style "MAP" files to use in translating pixel locations to URL's.

Note that some browsers (such as NETSCAPE 2.0) support "client side mappable images", which require no action by the server (but which require an HTML element not understood by many other browsers).

IN-HOUSE

IN-HOUSE refers to clients that are "in-house"; specifically, they have had INHOUSE privileges assigned to them. The idea is that one often wants to differentiate members of your "organization" from the rest of the world, and place fewer limits on what they can obtain from the server.

Macrospace

Marospace is best thought of as a global procedure cache used by OS/2. When REXX programs are asked to load external procedures, they first look in macrospace. For efficiency reasons, SRE-FILTER makes extensive use of macrospace; both as a procedure library and to store copies of it's user-configurable parameter files.

Response Header

The response header contains "meta-information" about the requested document. GoServe automatically sends a few response headers (such as content length and file creation date). In addition, using the LINK and HTTP-EQUIV tags in the <HEAD> portion of your document, you can instruct SRE-FILTER to automatically add other response headers.

Searchable Index

A searchable index is a document that points to a file that is to be searched. One can think of a searchable index as:

.. the front end to a gateway progray, and the file you search as the database represented by the document.

Typically, a searchable index contains the <ISINDEX> element.

Server Side Includes

Server side includes refer to on-the-fly modifications of requested HTML documents. Inclusions can be static, in which case the use of server side includes is mostly to benefit the creation and maintenance of these documents. Dynamic includes refer to information that changes, such as the current time and date -- obviously, these can not be specified in the document a priori, but must be determined at the time of request.

Server Side Processing

Often, the server provides computational services to clients. An example of this is a client specified search of a database, with the results displayed using an 'attractive" HTML document (generated just for this search). Or, the client might request a map of some portion of the U.S, displaying a choice of geographic features. Such actions require the server to execute some kind of program (perhaps a REXX program, or perhaps some other executable).

Server Side Processing Request

A Server Side Processing request is, generically speaking, "a set of parameters, sent by a client, and an action name, that dictate Server Side Processing". Often these are generated by a client responding to a FORM element in an HTML document (alternatively, they may be "hand coded" into a URL included in a HTML document). Server Side Processing requests are recognized by:

If the GET method was used: the presence of a ?options string after a "non-HTML" action name; where options contains the "set of parameters".
Notes:

• SRE-FILTER assumes that, regardless of the presence of a ? in the request string, all action names that end with a .HTM or .HTML are requests for HTML documents (that is, are not requests for server side processing),
• Actions which require no parameters must have a ? trailing the action name.
• Server side programs are sometimes referred to as gateway programs.

If the POST method was used, SRE-FITLER assumes a Server Side Processing Request, with the request string treated as the action (which identifies the program to run), and the "set of parameters" contained in the "body" of the request.

STEM variables.

STEM variables are REXX's way of implementing arrays. A STEM variable consists of a NAME.INDEX1.INDEX2 syntax (that is, with a . used to indicate "array indices"). SRE-FILTER uses STEM variables for several of it's configuration parameters.

SUPERUSER status

Clients with SUPERUSER status are granted full privileges. Currently, this includes:

Never having to logon (SUPERUSERS are INHOUSE users)

Automatically granted VIEWMESS privileges (can read "message boxes")

Automatically granted CONTROL privileges (can perform remote server resets)

File uploads are never blocked.

URL: Uniform Resource Locator.

URL's are a scheme for specifying Internet resources using a single line of printable ASCII characters. A URL shoud contain a protocol, domain name, port number (optional), the location of the resource, and an (optional) "search and control" string.
In this documentation, the URL term connotes "a link coded into an HTML document". Upon selecting such a link, the client sends back a "request string" equal to this URL (plus other information).
Example: http://www.econ.ag.gov/calc/calc.htm
If this URL were selected by a client, the resulting request string would be calc/calc.htm

URL character encoding

Since several characters have very specific meanings in the HTTP protocol (such as the & and the > characters), and since spaces are not allowed in request strings, a set of character encoding rules are needed to transmit such characters.

Caution: When handcoding URL's with option lists following a ? and seperated by & characters, you must encode the & character.

For example:

• INCORRECT: <A HREF="/GETAFILE?dir=PUBLIC/&showdate=YES">
• CORRECT: <A HREF="/GETAFILE?dir=PUBLIC/&amp;showdate=YES">

Web Browser

A Web Browser is a program that can communicate over the Internet, and that is capable of displaying HTML documents. NetScape, Mosaic. and IBM Web Explorer are examples of Web Browsers.

Wildcard matching

Wildcard matching use the * as a wildcard character in a natural fashion.
Examples:

  /JOE/*  will match /JOE/FOO.HTM
  /JOAN/SRCH.HTM?*  will match /JOAN/SRCH.HTM?search+me
  /JOAN/SRCH.HTM?*  will NOT match /JOAN/SRCH.HTM
         (/JOAN/SRCH.HTM* will match BOTH these examples)
  /PETS/*INDEX.HTM will match
     /PETS/INDEX.HTM, /PETS/CAT/INDEX.HTM and /PETS/PUPPY/LAB/INDEX.HTM
             but will NOT match
     /PETS/CAT/PUREBRED.HTM

SRE-FILTER files that support wildcard matching are: ALIAS_FILE, RECORD_ALL_FILE, SEND_FILE, ACCESS_FILE, and the PUBLIC_FILE stem variables.
The COUNTER_FILE does not support wildcard matching.

Wildcard matching with substitution

Wildcard matching with substitution is similar to wildcard matching. However, rather then being a "many to one" match, it is a "many to many" match.
The basic rule is that both a "target" and a "replacement" should contain * characters. When a wildcard match between the target and a candidate occurs, the "covered portion of the candidate" is inserted into the "replacement". In other words, the * character in the replacement is deleted, and the "covered portion" is inserted.

Example:

• If the request string is: project/jillwork.htm
• and there is an alias of: project/* /research/ongoing/*
• SRE-FILTER will convert the request string to /research/ongoing/jillwork.htm

Working Directory

The Working Directory in the directory containing GOSERVE.EXE (typically, \GOSERV). You should copy the various SRE-FILTER files to it (see the installation section for details).
Note: the "working directory" and the "server directory" should be the same directory, with the Working Directory set in the properties list of the GoServe icon, and the "server directory" set using the SERVDIR variable.